.____________________________________________________. | | | S E C R E T S O F F L A S H | | | \====================================================/ How to make the most of Flash's DO language: Things they never seem to tell you at the store. _________________________ B Y A L F A S O L D T ------------------------- Technology Writer, Syracuse Newspapers and Newhouse News Service Computer pagination trainer and programmer, the Herald-Journal, the Herald American and the Post-Standard Syracuse, New York Copyright (C) 1992 by Al Fasoldt. All rights reserved. P A R T 1 : I N T R O D U C T I O N --------------------------------------- This article is for newcomers and experienced Flash users alike. Many parts of this guide contain information that may not be generally known to most users. Flash was distributed by Antic Software, a company that is no longer doing business. However, Flash is still available from ST and TT software outlets. Many of these tips may also be applicable for users of Flash II, a new telecommunications program from Missionware. Flash II was scheduled to be released by mid-1992. P A R T 2 : W H A T T H I S I S A L L A B O U T ----------------------------------------------------------- Flash, a telecommunications program for the Atari ST, was distributed by Antic Publishing's software division from the mid-1980s until the company ceased operation recently. Flash is now an orphan in the marketplace, although the copyright law in the United States and elsewhere still protects the software from infringement. Without direct manufacturer support, however, the only way Flash users can receive help is through the individual efforts of experienced Flash programmers who are willing to take the time to offer advice and assistance. One avenue for such help is the nationwide network of telecommunications services. These services, which include GEnie, Compuserve, BIX, Delphi and America Online, have active ST users who have used Flash for five or six years. Many of them have written extensive Flash scripts that take advantage of Flash's powerful programming language. As one of those Flash programmers, I am offering this expanded documentation as a means of keeping the thousands of current Flash users up-to-date on how to use Flash's DO language -- its scripting commands -- in ways that may not be obvious in Flash's original, sparse documentation. This document is free, and I encourage you to share it in electronic or printed form with anyone else. But in doing so you must observe these three common-sense requirements: 1. This document cannot be distributed in any altered form. This means you must not make excerpts of it, and you must not remove the author's name and copyright notice. 2. This document must not be distributed with any other document or software program, other than the author's Flash DO files and any other support files that are archived with this text file. This means you must not include Flash itself with this documentation if you share it with anyone else. 3. The author cannot be responsible for the use or misuse of any of the files included with this documentation. This means you are on your own when you try out the DO files and the support program(s), and cannot blame me if any of them cause a problem. If you have suggestions or comments, or would like your own DO files or support programs included in revisions of this archive, you can reach me at any of these addresses: Email: GEnie - "a.fasoldt"; BIX - "afasoldt"; AOL - "Al Fasoldt" U.S. mail - Syracuse Newspapers, Box 4915, Syracuse, NY 13221 ** A note about Flash versions ** The last release of Flash was Version 1.61. However, this version is usually referred to as Version 1.6. According to the authors of Flash, Version 1.6 was never actually released, and all versions that carry a "1.6" designation are actually 1.61. This documentation is intended for users of 1.6/1.61 only, since the script language was made more powerful in that release. If you own an earlier version of Flash, an upgrade to 1.6/1.61 is highly recommended. A patch file distributed free on many telecomm services will automatically upgrade previous versions to the last version. P A R T 3 : W H A T A R E S C R I P T S A N Y W A Y ? --------------------------------------------------------------- ** Scripts tell the computer what to do ** Many telecommunications programs have built-in scripting abilities. In other words, they are able to follow a written list of instructions much like the scripts that actors must follow. A telecomm script, like the ones used in plays and movies, contains lines that must be said (or sent to another computer, in the case of the telecomm script), and it may contain such things as cues, also. (The computer may be told to wait until a certain time has passed before it does something else, for example.) But telecomm scripts usually have many more features than this. The scripting facility built into Flash, called the "DO" language, can instruct the computer to perform any of these functions: - Suspend action until a specific time - Wait to get an exact word or phrase from the other computer before proceeding - Show a dialog box on the screen and ask for user input - Ring the computer's bell (and even ring the bell on the other computer) - Dial a number and redial it up to 99 times if it's busy - Delete a file on a disk drive - Check to see if a particular file exists - Check the contents of any file, line-by-line - Run a program - Program and execute a function key remotely - Check to see if an upload or download was successful and try it again, if desired - Look back to see what the last information the other computer sent actually said And much more -- so much more, in fact, that many casual Flash users are unaware of the full power of the DO language. For example, a DO script can assemble a text file from information that is sent across from another computer and save that text with the date as part of the name. For another example, a DO script can even modify itself by creating a new DO file and then running it. You'll see how to do all of this and more in this documentation. But first, we'll need to understand the basic way a DO script is put together. ** A note on the way commands and keystrokes are shown ** Keyboard keys are listed in the text with angle brackets before and after them, like this: . Key combinations are shown the same way, with a hyphen between them, like this: . Many commands are not complete without parameters. In simple terms, parameters make a command more specific. The place where parameters go is shown like this: [...] Quotation marks are sometimes used to set off parts of the text, like this: A ".DO" file extender. Do NOT type the quotes when you follow the example. However, quotation marks are also used within DO scripts for various purposes. Whenever an example of quotes within a DO script is given, you will see a reminder that the quotation marks MUST be included in the script. Finally, grammarians who are reading this carefully may notice that this text breaks the rules of punctuations freely. Whenever this is done, it's for clarity. (If you're wondering what I am referring to, here's an example. In DO script writing, we use ">". The period probably should have gone inside the quotation marks -- like this: ">." -- but that would make the example a lot harder to follow.) A note on the way pathnames are shown ------------------------------------- By convention, filenames that are listed in the parameters sections of this document have the name "filename.ext"; drives are listed as "d:" -- with the colon included as part of the required drive specifier. The "d:" does not stand for any particular drive; it can be "a:" through "p:" on some STs and TTs and "a:" through "z:" on others. The ST and TT operating system uses a common method of indicating which command parameters are pathways (drives and folders) and which are files. Pathways can be relative or absolute, depending on how they are written. An absolute pathway always has a backslash at the end, whether a filename follows it or not. A relative pathway does not have a slash after it. And files, in turn, never have slashes after their names. Here are some simple examples: An absolute pathname: c:\flash\dofiles\ This indicates that Flash should perform some operation in the folder named "dofiles" inside another folder named "flash" in the root directory of the c: drive. A relative pathname: c: This indicates that Flash should perform some operation in whatever pathway it was already using on the c: drive. It may seem obvious to some that the "c:" could be left out, but this is not necessarily the case. For example, if Flash's default pathway had been "c:\flash\" and was then changed to "a:\messages\", any time Flash returns to "c:" (without a backslash) it will arrive at the location it was in the last time it accessed the "c:" drive. A pathname and filename: c:\flash\dofiles\callbbs.do NOTE: You must be sure to include the backslash between "dofiles" and "callbbs.do" so that the operating system does not look for a file named "dofiles" in the "c:\flash\" directory. P A R T 3 : H O W S C R I P T S A R E W R I T T E N ------------------------------------------------------------- Here are guidelines for writing and executing scripts. All of them are explained in detail later. In Flash DO scripts, commands should be: 1. Written in plain text, also called ASCII. 2. Written on a separate line -- until the script has been tested and is known to work properly. You then have the option of combining many commands on one line. 3. Preceded by a ">" character. 4. Followed by a "|" character. 5. Written with comments at the beginning giving the name of the script and at any point in the script where complicated commands are operating. 6. Written in lower case. Flash DO scripts can be: 1. Any practical length (although short scripts execute faster than long ones). 2. Named anything you want, with any choice of filename extender -- although you should standardize the extenders to make scripts easy to organize. 3. Executed from any folder or from a root directory on a floppy disk, hard disk or ramdisk. Flash scripts can be executed in five ways: 1. From Flash's command line, which is accessed from the terminal screen by pressing the key. 2. From an alt-key combination. 3. From a function key. 4 From another script. 5. From Flash itself, automatically, whenever Flash runs. ** The write of passage ** Flash scripts must be written in plain text. ------------------------------------------- Word processors usually store their text files in a form that includes codes for such things as boldface, font sizes, line centering and other display attributes. While this is perfectly fine for documents that are printed out, it causes a great deal of trouble for texts that are used as script files. These texts must not have any word-processing codes at all; if they do, the program running the script will either stop running the script or, in one of the favorite phrases of programmers, will "do something unpredictable." The easiest way to make sure this doesn't happen is to write Flash scripts by using Flash's own text editor. The Flash text editor is powerful enough to serve as a primary text editor for all script writing, although it does lack many of the niceties of the current standard text editor for the ST, STeno, from Gribnif Software. (The screen fonts can be made large or small in STeno, for example, and -- best of all -- STeno can be run as a GEM desk accessory while you are running Flash.) But Flash's own text editor is ideal if you do not own STeno. Flash's editor offers search-and-replace functions, block-delete and block-save operations, text-file insert, easy scrolling by the cursor keys or GEM window bars, and two big advantages -- immediate access to Flash's GEM-bar menus, including the Help menu, and the ability to test a script as you are writing it. No matter which text editor you use, you must turn off word wrap before you write or load a script file. You do not want the text editor to decide where lines end; it probably will wrap some lines around and ruin the script. Flash's editor can load texts with inordinate line lengths (STWriter files, for example, can have line lengths of hundreds or even thousands of characters), but Flash itself runs into difficulties if scripts include lines that are longer than 102 characters. This means that you can write scripts with line lengths of, for example, 90 columns (a "column" in text processor terminology contains one character), but unless you are careful you may have a problem making sense of your scripts if they are written that way; since Flash's editor will not show any characters past the 76th column without horizontal scrolling, you may forget that some lines extend past the right edge of the screen when you are checking your scripts. Play it safe and keep your line lengths down to 65 to 75 columns. Both STeno and Flash's own editor save texts in ASCII. The word stands for the American Standard Code for Information Interchange, and represents a set of standards that nearly all personal-computer manufacturers follow for the internal codes that are used for all regular keyboard characters. In other words, the letter "A" has the same ASCII code -- "10" in decimal notation -- on the ST, an IBM PC, or even an AT&T teletypewriter. (The ASCII standard also defines the common codes for such "characters" as and , which normally cannot be seen on a computer screen because they usually signal the computer to do certain things. However, both STeno and Flash's own editor allow you to enter control characters directly into a script.) However, if for some reason you would rather write Flash scripts on a word processor, such as WordPerfect, WordUp, That's Write, WordFlair, WordWriter, 1st Word or STWriter, you will have to make sure you save the scripts to disk as ASCII files. Some word processors have an ASCII Save option and others can only save files as ASCII when they are "printed" to a disk file. If you choose this method, be sure to set the left margin at "0" and the right margin at about 75, and, if necessary, set top and bottom margins to "0" also. Then, after you have saved the scripts as ASCII files, run Flash and load them, one by one, into Flash's text editor and look them over carefully. (Turn off Flash's word wrap whenever you do this.) Then save them again from within Flash. (A big drawback to using a word processor for writing scripts is that the word processor is not likely to let you insert control characters in the text that it saves as ASCII. The typical exception is , which has no use in most script files anyway. And if this isn't enough of a reason to avoid a word processor when writing scripts, there's the added trouble of reconverting ASCII-based scripts back to your favorite word processor's format whenever you want to edit them. My advice: Use STeno or Flash's own editor.) Scripts should be written with each command on a separate line. --------------------------------------------------------------- Scripts are written in a kind of code that looks like English words or abbreviations. Until you become an expert at script writing and script editing, you should always write each command on a line of its own. This makes the task of debugging a script much easier, since you'll have a lot better chance of understanding what each command is trying to do when they're separated. Flash does not require each command to be on a separate line, however. It will run scripts without a problem if commands are bunched up. In fact, scripts will run slightly faster that way. (Technically, the reason is that Flash parses or interprets scripts one line at a time when they are run, and it will parse a few long lines faster than a lot of short ones.) But until you are entirely comfortable with the way each command works, you're better off keeping them on separate lines. Commands must be preceded by a ">" character. --------------------------------------------- Commands must have a right-facing angle bracket in front of them. (You don't have to put the angle bracket right next to the command; you can put spaces between them if you want. For more on this technique, see Appendix XX, "Making scripts more readable.") The angle bracket, also called the "greater-than" symbol, is the only way Flash can tell that the word that follows the bracket is an actual command. The ">" character should be considered as part of every Flash command, even if commands are bunched up on a single line. Every time Flash sees an angle bracket, it expects that the next characters it sees will be a command. (Flash will ignore that bracket and any of the other special characters used in scripts if they are enclosed in quotes, however.) Commands must end with a "|" character. --------------------------------------- Once Flash encounters a ">" character in a script, it accepts all the characters EXCEPT SPACES following the ">" as parts of a command until it comes to a vertical bar symbol. The "|" symbol is shown on the ST keyboard, in typical IBM fashion, as two short vertical bars, one on top of the other. (You get it by typing .) The vertical bar symbol has a double job in Flash. It also stands for a carriage-return/line-feed combination -- a , in other words. We'll see how Flash uses "|" for just a later. Commands should be commented. ----------------------------- A comment in a programming language is any part of the script that is ignored when the script is run. In Flash, a comment is indicated by two asterisks placed right after a ">" symbol. At the end of each comment, Flash requires a "|" symbol. A typical comment might look like this: >** This is the start of the CALLBBS routine.| Comments can be any reasonable length. Even though it seems obvious that comments should be self-contained on one line, this is not the case at all. Flash considers any length of text a comment if it starts with a ">" and ends with a "|". This means that entire paragraphs or groups of paragraphs can be comments. (In testing, I used a text more than 180K long as a comment, without a problem ... except, of course, for the dreadful slowdown in the execution of the script.) This unusual property allows programmers to treat comments as blocks of text, readily set off from the main sections of the script. Comments could look like this: >** This part of the script calls the Zork BBS and waits for 2 minutes for an acceptable connection. If it does not find one, it calls back 15 minutes later. | Note that both the start-comment and end-comment command characters -- ">**" and "|" -- were on lines of their own. This may seem unorthodox, but works fine. It is especially easy to read the comment, since it does not have any asterisks or vertical-bar symbols as part of the comment text. Experienced programmers always place comments in their work; they have no choice, because the alternative would be to trust everything to memory. Commented commands and subroutines are also a sign that the programmer knew what he or she was doing. Many veteran Flash users have seen scripts that performed complicated tasks in needlessly serpentine ways, largely because the script writer had gotten lost deep within the script and had to wiggle within the commands to get back out. Scripts that are commented can help avoid this, and as a result the scripts will be more powerful and usually will run faster. Remember that comments slow down the execution speed of DO scripts. Even though Flash does not treat anything within a comment as a command, Flash looks through all comments for improper command syntax. (This is bizarre, to say the least, but it cannot be avoided.) Flash will not allow unpaired quotation marks in comments, for example. This means you will not be able to use contractions in comments unless you spell them with double apostrophes -- like this: "Don''t use single apostrophes; Flash can''t execute the DO script otherwise." If this looks as silly to you as it does to me, just avoid unnecessary contractions, apostrophes and quotation marks altogether in DO files. Commands should be written in lower case. ----------------------------------------- Some scripting languages require upper-case commands, and some require lower-case commands. Flash can accept them either way, so you'll probably find that lower-case entries are better because they are easier to read. Two exceptions are any single-letter variable names, which in Flash are indicated by a dollar-sign symbol followed by a letter from A to Z and which can be confusing in lower case, and the Flash command for a label, "L", which can be misidentified as the number "1" if it is written in lower case. ** The play's the thing ** Scripts can be any practical length. ------------------------------------ You will not find a limit to DO file lengths in any normal use. My tests have shown that scripts longer than 100K caused no problem other than a severe slowdown in execution. If you write a very long script that seems to take a few minutes to load and run, try breaking the script into a couple of parts and running those parts from a master script. Scripts can have any name you want. ----------------------------------- Alan Page, co-creator of Flash, began the convention of naming scripts with a ".DO" extender. (A filename extender follows the period at the end of the filename and can be one to three characters long.) But there's nothing that prevents you from using any other extender or, of course, no extender at all. Flash will run any DO file regardless of its name. But you'll find it a lot easier to keep track of your scripts if they all have the same filename extender, whether it is ".DO" or ".SCR" or something else. I suggest the conservative course of sticking to "filename.do" to avoid confusion, since no other programs for the ST currently use the ".DO" extender. Scripts can be stored and run from any folder or path. ------------------------------------------------------ In its default state, without any prior modification of its file paths, Flash expects to find scripts in the same folder or path that it was run from. However, you can specify any other location when you run a DO script, or you can change the default directory through a "cd" (change directory) command within a script. You can also issue the "cd" command from Flash's command line, a function key or the GEM menu bar in Flash. You can even use a special script to search all possible paths for DO files automatically, letting it set the default once it has found the files. ** Running in place ** Run a script from the command line. -------------------------------------- The usual way of running a DO file is to use Flash's command line. The command line appears at the bottom of the terminal screen (not the GEM window screen) any time you press the key. When the command line appears, type "do" and a space and then the full name of the script -- with the pathname preceding it, if necessary -- and then press . Run a script by pressing . --------------------------------- From Flash's terminal screen, you can press to open a file selector from which to choose a DO script. Double-click on the script you want and it will execute. Run a script from a function key. --------------------------------- Using Flash's function-key editor, you can program a function key to run a script. Type the same command into the function key template that you would type at the command line. Make sure the function key command ends with a "|" symbol, which is Flash's equivalent of a key, or the script will not execute. (Flash waits for you to press in that case.) Note that function keys are quite powerful. They can be programmed from within a script, and can even be used within scripts as "gosubs." Run a script from another script. --------------------------------- This is so obvious that it may be missed by some users: Flash's scripts can be chained or nested. This offers a particular advantage to a programmer, since scripts can be broken up into easy-to-write sections and run separately. Ideally, a master script should be written to run sub-scripts, as will be explained in some detail later. The Flash command to run a DO script within another script looks like this: >do pathname\filename.do| Run a script automatically when Flash boots ------------------------------------------- Flash's "auto" function, which is perhaps the least known of the program's main features, will instruct Flash to execute a single command when it is first run. This seems fairly limiting, but it is not -- if you make that single command the "DO" command, which runs a script. Since a DO script can contain any number of commands, there is no real limit on what Flash can do, automatically, when it boots up. Setting up the "auto" function involves nothing more than pressing the key from Flash's terminal screen, typing "auto," a space, the command you want executed on bootup, then . You must then save Flash's configuration file to the filename "FLASH.CNF" -- the configuration file it always looks for and loads when it runs. P A R T 4 : B A S I C F L A S H C O M M A N D S ------------------------------------------------------ The abbreviated command name is listed as the primary one, with the longer name, if any, listed in parentheses. While Flash often has two ways of giving a particular command -- "baud" and "ba," for example -- by convention, the short name is preferred. With the exception of "load," "log" and "ifin," Flash itself does not scan past the first two letters of a command name anyway. Parameters, if any, should be placed after the command name. Commands that take parameters are listed this way: >ba [...] If parameters are optional, commands are listed this way: >mf [...optional] Please note that in each case in which a variable can be substituted for a parameter, more than one variable can be used if they are concatenated (combined without spaces between them). For example, if the variable $X contains the characters "filename" and the variable $Y contains the characters ".ext", you can give Flash the command "lo ca $X$Y" and it will understand it as "lo ca filename.ext". The building blocks ------------------- Many script commands help build the structure of a DO file. They include labels, jumps and conditionals. Within the structure, variables can help keep the script from becoming top-heavy. These commands are presented first to point out ways to build your scripts as economically as possible. - LABELS Command: >L: [...] (label) Action: Marks a line in the script that can be quickly accessed through a "jmp" command. Flash skips everything between its previous point in the script and the label, and begins its next execution at the line following the label. The label should be by itself but does not have to be. Labels can be as long as the width of the screen, but short labels are best. Labels must not include a space. Parameter: labelname or label_name (Can be written in upper or lower case or any mixture of the two, but Flash does differentiate between capital letters and lower-case letters when it looks for labels. This means "labelname" is not the same as "LabelName") Examples: >L: BeginCall| >L: a_really_long_label_but_it_is_OK_if_it_has_no_spaces| - JUMPS or GOTOS Command: >jmp [...] (also abbreviated "jm") Action: Forces the script to look for the label given as the parameter and then to execute the command following the label. It is a misconception that labels must be on lines by themselves; they do not need to be. (See one of the examples below.) The parameter must be spelled exactly the same as the label, including upper- and lower-case letters. Note: The "jmp" command works as a standard "goto" in scripting languages, not as a "gosub." That is, command execution will not return to the line following the "jmp" command. However, Flash has an undocumented "gosub" feature, explained in "How to use 'gosubs' in scripts" below. Parameters: labelname or label_name Examples: >jmp BeginCall| >jmp a_really_long_label_but_it_is_OK_if_it_has_no_spaces| Context examples: >L: begin| >ifi $X "Yes" jmp end| >ifi $X "No jmp begin| ... >L: start|>wt 08:45:00|>do callbbs.do|>jmp start| - VARIABLES Command: $X [...] Action: Places a character string (any letters or characters) into a storage area represented by "$A" through "$Z". This is the most simple of many ways variables can be set. The parameter does not have to be in quotation marks, although the special symbols ">" and "|" must be set off with single quotes if they are assigned to a variable. There is one other variable in Flash. It's "$!", which represents the contents of Flash's single-line input buffer (the area where incoming data is stored while it is being received from the modem). You can't assign your own character string to "$!", but otherwise it works like the other variables. Parameters: [any letters or numbers; the limit is just over 100] $Y (any other variable) Examples: >$X c:\download\clock.prg| >$X $Y| >$Z '>Hello|'| Context examples: ** Using a variable with an Xmodem upload command ** >$X a:\temp\browneye.spc| >ul xm $X| >** Sets X to a filepath and filename, then uploads that file. | ** Setting one variable from another and combining variables ** >$X c:\letters\| >$Y $X| >$Z tomother.txt| >ul xm $Y$Z| >** Sets X to a pathname and then sets Y to X. Sets Z to a filename, then combines Y and Z for the Xmodem upload parameter. | Regular variables and the buffer variable are covered in greater detail below. - COMMENTS or REMARKS Command: >** [...] Action: Treats text following the "**" as a comment or a remark until the next "|" is reached. Comments can be as lengthy as you want, but long comments slow down the script. Although Flash is supposed to ignore the text in a comment, it checks comment lines for command syntax and will show an error if it encounters a non-paired quotation mark (either a single-quote or a double-quote mark) within the comment. If you use contractions within comments, they must have double apostrophes. Comments can be dressed up with tabs and internal spaces, and they can be set off in their own text blocks. Parameters: [any text] Example: >** This is a comment. The text can start on its own line. Blank lines are OK. The vertical bar symbol ("|") can be placed on its own line after the comments. Note that if the bar is surrounded by quotes, Flash will not count it as an end-command character. | - SCRIPT EXECUTION Command: >do [...] (execute a script) Action: Run a script within another script. The nesting limit is three. Be careful when running scripts from a master script, since you may exceed the nesting limit without realizing it. The "do" command is one way that Flash provides the equivalent of a "gosub" -- a command that branches to another set of instructions and then returns when the other instruction is finished. (The return takes effect at the next command from the one that called the sub-script.) You must give the full filename of the script; Flash will not run scripts with ".DO" extenders unless ".DO" is specified in the "filename.ext" parameter. Parameters: c:\filepath\dofile.ext $X (any variable containing a filespec) Example: >do callbbs.do| >do c:\flash\dofiles\settime.do| >do c:\flash\do\$P| Context example: ** Scripts that are run from a master script based on the day ** >L: top| >do c:\flash\do\setday.do| >ifi $D "Monday" do callbix.do| >ifi $D "Monday" jmp cleanup| >ifi $D "Tuesday" do callbbs.do| >ifi $D "Tuesday" jmp cleanup| >ifi $D "Wednesday" do getmail.do| >ifi $D "Wednesday" jmp cleanup| ... >L: cleanup: >do arcmsgs.do| >wt 00:01:00| >jmp top| The setup --------- Some of the script commands deal only with communications port parameters. They are usually set only once for each session in which Flash is run. - BAUD RATE Command: >ba [...]| (baud) Action: Sets the baud rate, known more accurately as the bits-per-second rate. Your modem must support the rate you choose. If you are setting up a direct connection through a null-modem cable, you may find text transfers falter at 9600 and 19,200 bps. Parameters: 11 [110 bps] 30 [300 bps] 60 [600 bps] 12 [1200 bps] 24 [2400 bps] 48 [4800 bps] 96 [9600 bps] 19 [19200 bps] $X [any variable containing a bps number] Examples: >ba 2400| >ba $X| - DIALING Command: >di [...] (dial) Action: Tells Flash to dial a number. If the "#" parameter is given, Flash dials the number following the pound sign. If a name is listed as a parameter, Flash looks in the dialing directory for the first name that matches the letters given in the parameter and then dials the number listed for that entry. Parameters: # (followed by a telephone number) "name" (a listing in the dialing directory; it can be abbreviated) Examples: >di #123 456-7890| >di harry| - DUPLEX Command: >du [...] (duplex) Action: Sets the echo to remote or local (full or half). This is loosely called full or half duplex, although the term is not accurate. In remote echo (full duplex), what you see on your screen comes from the other computer, even if it is what you are typing. (The signal goes out to the other computer and is echoed back to yours for display on your screen.) In local echo (half duplex), the words you type are displayed by your own computer. Parameters: fu (full) ha (half) / (a toggle, from full to half or vice versa) $X (any variable containing "full," "half" or "/") Examples: >du full| >du /| >du $X| - ECHO Command: >ec [...] (echo) Action: Sets the echoplex, in which Flash can send back all characters received from the remote computer, regardless of the "duplex" setting. With echo set to "off," flash does not send any characters back. Parameters: on of (off) / (a toggle, from on to off and vice versa) $X (any variable containing "on," "off" or "/") Examples: >ec on| >ec /| >ec $X| - HANGUP Command: >hg (hang up) Action: Hangs up on the other modem or on the dead line. Parameters: none Example: >hg| - LINE FEEDS Command: >lf [...] ("line feeds"; the command must be given in its abbreviated form only) Action: Changes the way Flash handles the ends of text lines that are received or transmitted in text transfers. With line feeds on, every is converted to a /line-feed combination. With line feeds off, nothing is converted. Set this to match what the other system expects. Parameters: on of (off) / (a toggle between "on" and "off") $X (any variable containing "on," "of" or "/") Examples: >lf on| >lf /| >lf $X| - MODEM CONNECT MESSAGE Command: >mc [...] ("modem connect"; the command must be given in its abbreviated form only) Action: Tells Flash what your modem will echo back to Flash, in English, when another modem answers a call that your modem makes. Parameters: CONNECT $X (any variable containing the desired modem-connect text) Examples: >mc "CONNECT"| >mc $X| - MODEM FAIL MESSAGES Command: >mf [... optional] ("modem fail"; the command must be given in its abbreviated form only) Action: Tells Flash which of the predetermined "modem fail" messages listed in the dial directory will echo back to Flash if a dial command is not successful. If you do not have any "modem fail" messages listed in the dial directory, use the "text" parameter or the variable instead. (Or edit your dial directory properly.) Parameters: [none] (if no parameter is given, Flash uses the default parameter, which is #1) 1 (message #1 in the dial directory) 2 (message #2 in the dial directory) 3 (message #3 in the dial directory) 4 (message #4 in the dial directory) "text" (any message, such as "BUSY") $X (any variable containing a modem-fail message) Examples: >mf| >mf 2| >mf $X| - EMULATION MODES Command: >mo [...] (mode) Action: Chooses the terminal emulation mode. The standard mode for STs is "at" (Atari). You must match the other computer's mode. Parameters: an (ansi; this lets Flash show some of the text attributes of the ANSI standard, used by many PCs) at (atari; this is also called "VT52" and is a standard PC setting) vi (vidtex; a once-popular display mode that can display graphics along with text) $X (any variable containing "an," "at" or "vi") Examples: >mo at| >mo $X| - DIALING PREFIX Command: >mp [...] ("modem prefix"; the command must be given in its abbreviated form only) Action: Tells Flash what text to place in front of the modem dialing command. This is usually "ATDP" for pulse-tone (rotary dial) lines and "ATDT" for touch-tone lines. Parameters: "ATDP" "ATDT" "TEXT" (any modem dialing string prefix; capital letters are safest) $X (any variable containing a dialing string prefix; capital letters may be necessary) Examples: >mp "ATDT"| >mp $X| - DIALING SUFFIX Command: >ms [...] ("modem suffix"; the command must be given in its abbreviated form only) Action: Tells Flash what text to place after the modem dialing command. Generally not needed. Parameters: "TEXT" (sometimes can be lower case) $X (any variable containing a modem suffix; capital letters may be necessary) Examples: >ms $X| - PARITY Command: >py [...] ("parity"; the command must be given in its abbreviated form only) Action: Sets the parity of bytes that are sent and received. By itself, parity means little, but you should match Flash's parity with the setting used by the other computer. Parameters: no (none) od (odd) ev (even) $X (any variable containing "no," "od" or "ev") Examples" >py no| >py $X| - NUMBER OF REDIALS Command: >re [...] (redial) Action: Tells Flash how many times to redial a number if it receives a "modem fail" message (if the number is busy or if for some reason the modem can't get through). Note that a redial setting of 1 means Flash will dial twice if necessary. Parameters: 0-99 (any number from 0 to 99) Example: >re 5| - BACKSPACE BEHAVIOR Command: >ru [...] (rubout) Action: Changes the way the key behaves during on-line communication. With "ru" on, deletes characters on both screens. With "ru" off, merely backs up the cursor. Parameters: on of (off) / (a toggle between "on" and "off") Examples: >ru on| >ru /| - STOP BITS Command: >sb [...] ("stop bits"; the command must be given in its abbreviated form only) Action: Sets the number of stop bits in bytes that are sent and received. By itself, this setting means very little, but you should match Flash's setting with whatever the other system is using. Parameters: 1 2 $X (any variable that contains "1" or "2") Examples: >sb 1| >sb $X| - STRIP BIT Command: >st [...] (strip) Action: Sets the "strip-bit" toggle on or off. The bit that is stripped is the "high bit," which determines whether a character is "high ASCII" or not. This functions only in text capture and text send. Parameters: on of (off) / (a toggle between "on" and "off") Examples: >st on| >st /| - BYTE LENGTH Command: >wl [...] ("word length"; the command must be given in its abbreviated form only) Action: Sets Flash's byte length to 7 bits or 8 bits. This is called the word length, although it has nothing to do with English words. Nearly all PC communication uses 8-bit byte (word) lengths these days. Parameters: 7 8 $X (any variable containing "7" or "8") Examples: >wl 8| >wl $X| - Xmodem TYPE Command: >xm (Xmodem) Action: Determines the type of Xmodem that Flash will use, and a few other aspects of file transfers. Parameters: 7 (7-bit Xmodem; rarely used any more) 8 (8-bit Xmodem; the standard bit setting) C (CRC Xmodem, the preferred error-checking setting; absence of the "C" parameter will force Flash to choose an older, less satisfactory setting, usually called checksum Xmodem) R ("regular" block lengths of 128 bytes K (1-kilobyte block lengths) T ("Tight" timing of Xmodem block transfers, for good phone connections) L ("Loose" timing of Xmodem block transfers, for poor phone connections) S ("Size-byte" padding of the last block in the transmitted file, used by Atari 8-bit systems) Z (Control-Z padding of the last block in the transmitted file, the standard PC and ST method) $X (any variable containing parameters as listed above) Examples: >xm 8CKZ| >xm $X| Sending and receiving files --------------------------- Flash's primary function as a telecomm program is to send and receive data in the form of files. Scripts make this easy. - UPLOADING Command: >ul [...] [...] [...] (upload) Action: Sends a file to another computer, either from a disk or from Flash's buffer. The upload command has either two or three parameters -- two if you are uploading from a disk file, and three if you are uploading from the buffer. Parameters: The upload command works this way if you are sending from a disk file: >ul as filename.ext (for an ASCII text upload) >ul xm filename.ext (for an Xmodem data or text upload) >ul yb *.* (for a Ymodem batch upload; wildcards are needed) The "filename" parameter can be in the form of "filepath\filename.ext" and it can be a variable, such as "$X," or a string of variables, if they are used for the path and filename. The upload command works this way if you are sending from the Flash capture buffer: >ul ca as filename.ext (for an ASCII upload of the entire buffer) >ul ca xm filename.ext (for an Xmodem upload of the entire buffer) It works this way if you are sending the part of the buffer that you have blocked off: >ul bl as (etc.) >ul bl xm (etc.) - DOWNLOADING Command: >dl (download) Action: In every respect but one, the download command works the same way as the upload command. The exception is the lack of any way to download, using the "dl" command,to the capture buffer. (You can, however, merely turn the capture buffer on and save all the text that is coming across from the other computer. This is, in effect, the same as an ASCII download.) Here are two sample command lines: >dl xm filepath\filename >dl as $X\$Y (the variables represent the filepath and filename) Creating and using blocks from a script --------------------------------------- If you have used Flash's built-in text editor for more than just reading texts, you may be familiar with its block functions. They are readily accessed from the first four function keys while you are using the editor (in the GEM screen). You can easily tell when you have blocked off text in the editing buffer, since it turns gray. Function key 1 marks the top of a block; 2 marks the bottom; 3 clears the marks, and 4 deletes the marked block. A GEM menu bar submenu allows you to save the marked block, and you can also append the block to a file and upload the block. All but one of these functions can be accessed from a DO script. The one that does not work directly in a script is the delete-block function. All the others can be done under control of the script. The typical way of manipulating text in the buffer is by turning the capture buffer on (with the "ca on" command string), saving the text that is entered, then clearing the capture buffer so that you can start the process over. (This technique is used in many of the DO file examples here.) But there may be times when you do not want to disturb the text in the buffer -- when you are saving all messages that come in from a BBS, for example. Yet you may also want to save parts of the buffer at the same time. That's where the block features come in handy. Here are the five block commands: >mk top (mark the top of a block) >mk bot (nark the bottom of a block) >mk cl (clear the block >ap bl filename.ext (append the block to a file) >sa bl filename.ext (save the block to a file) Here is a routine that uses block commands in a script: >do callbbs.do| >do sendmsgs.do| >se "Read|"| >ca on| >** buffer is now saving everything| >wa "Atari"| >mk top| >wa "no more messages"| >mk bot| >ap bl atarimsg.txt| >mk cl| >** saves Atari-related messages to a separate file.| >do sendmail.do| >do logoff.do| >sa ca bbslog.txt| >** saves entire capture buffer to log file.| Setting Flash's display and sound options ----------------------------------------- These commands control what Flash shows on the screen and what sounds Flash makes. - TIME SET Command: >sc [...] ("set clock"; the command must be given in its abbreviated form only) Action: Sets the system clock, using the 24-hour time given in the parameter. Parameters: "time" (in 00:00:00 form) Example: >sc 16:23:00| - CLOCK DISPLAY Command: >cl (clock) Action: Displays the time in the upper right corner of the screen. The time display is normally on unless Flash receives a "ti" (timer) command or an "rt" (reset timer) command. In these cases, "cl" redisplays the time. Parameters: none Example: >cl| - TIMER DISPLAY Command: >ti (timer) Action: Changes the clock display, at the upper right corner of the screen, to a timer. The timer is automatically set to zero every time a connection is made, or it can be reset to zero by the "rt" (reset timer) command. Parameters: none Example: >ti| - RESETTING TIMER Command: >rt ("reset timer"; the command must be given in its abbreviated form only) Action: Resets the timer within Flash to zero. The timer will not be shown on the screen unless the "ti" command is given. Parameters: none Example: >ti| - HIGH RESOLUTION Command: >hi (high) Action: Changes the monochrome-monitor to 48-line display mode. Does nothing if a color monitor is being used. Parameters: none Example: >hi| - VIEWING TEXTS OR VIDTEX GRAPHICS >vi [...] (view) Action: Display a text file on the screen, with screen-by-screen paging controlled by the . If the mode is set to "vi" (Vidtex), this command will display a Vidtex graphic as well. (Note that the command "vi" and the parameter "vi" are identically spelled but have different meanings.) Parameters: "filepath\filename.ext" (the optional path and optional full filename of the text to be shown; if a wildcard is used, Flash will display the first file it finds that matches the wildcard specification) $X (any variable containing the filespec as explained above) Examples: >vi c:\flash\flashdo.txt| >vi $X| - BELL SOUNDS Command: >b1 (single bell) Action: Sends a single bell sound to the monitor's speaker. It can be repeated as often as you want, by looping the command or by placing it many times in the script. Parameters: none Example: >b1| Command: >b2 (repeating bell) Action: Sends a repeating bell sound to the speaker for about 25 seconds. If you press any key during this time, Flash stops the bell sound and the script resumes. Otherwise, the script resumes when the tolling stops. Parameters: none Example: >b2| Setting and using directory paths and files ------------------------------------------- These are the commands Flash uses to operate on files. - LOADING A FILE Command: >lo [...] [... optional path, mandatory filename or wildcard] (load) Action: Load a file into Flash. The parameter is in two parts: The type of file to be loaded, and the path and name of the file. The file can be a text file loaded into Flash's text buffer using the "ca" parameter, a configuration file loaded with the "co" parameter, a dialing directory loaded through the "di" parameter, a set of function-key "bindings" (key presses assigned to function keys) loaded via the "fk" parameter, or translation tables to change incoming and outgoing characters loaded by way of the "tr" parameter. If you use a wildcard instead of a full filename, Flash will load the first file that matches the wildcard. CHECK THIS. Parameters: (Note: If you do not specify the location of the file to be loaded, Flash looks for it in the default folder, the one Flash was executed from.) ca d:\filepath\filename.ext (any drive and folder path) (capture buffer) co d:\filepath\filename.ext (configuration file; the default is FLASH.CNF, but you can name other configuration files any name you choose) di d:\filepath\filename.ext (dialing directory; the default is FLASH.DIR, but you can name other dialing directories anything you wish) fk d:\filepath\filename.ext (function-key assignments; the default is the wonderfully named FUNCKEY.DEF, but you can use any other name for optional function-key loaders) tr d:\filepath\filename.ext (translation tables; FLASH.TRN is the default, but any name is OK for optional tables) [...] $X (any variable containing d:\filepath\filename.ext) Examples: >lo ca c:\flash\messages.txt| >lo ca $X| >lo di c:\flash\localbbs.dir| - SAVING A FILE Command: >sa [...] [... optional path, mandatory filename] (save) Action: Save a file into Flash. The parameter is in two parts: The type of file to be loaded, and the path and name of the file. The file can be a text file saved from Flash's text buffer using the "ca" parameter, a configuration file saved with the "co" parameter, a dialing directory saved through the "di" parameter, a set of function-key "bindings" (key presses assigned to function keys) saved via the "fk" parameter, or translation tables to change incoming and outgoing characters saved using the "tr" parameter. Parameters: (Note: If you do not specify the location of the file to be saved, Flash saves it in the default folder, the one Flash was executed from.) ca d:\filepath\filename.ext (any drive and folder path) (capture buffer) co d:\filepath\filename.ext (configuration file; the default is FLASH.CNF, but you can name other configuration files any name you choose) di d:\filepath\filename.ext (dialing directory; the default is FLASH.DIR, but you can name other dialing directories anything you wish) fk d:\filepath\filename.ext (function-key assignments; the default is FUNCKEY.DEF, but you can use any other name for optional function-key loaders) tr d:\filepath\filename.ext (translation tables; FLASH.TRN is the default, but any name is OK for optional tables) [ ] $X (any variable containing d:\filepath\filename.ext) Examples: >sa ca a:\messages.txt| >sa ca $X| >sa fk c:\flash\fkey\funckey2.def| - CHANGING A DIRECTORY PATH Command: >cd [...] (change directory; the command must be given in its abbreviated form only) Action: Tells Flash to look in the specified path for all files and to use that path when saving files unless another path is specified in individual commands. Note: This command is identical to "dp". Parameters: d:\filepath\filename.ext $X (any variable containing a path and filename) Examples: (Note that the trailing slash is necessary.) >cd c:\flash\| >cd $X| - SETTING A DEFAULT DIRECTORY Command: >dp [...] (default path; the command must be given in its abbreviated form only) Action: Tells Flash to look in the specified path for all files and to use that path when saving files unless another path is specified in individual commands. Note: This command is identical to "cd." Parameters: d:\filepath\filename.ext $X (any variable containing a path and filename) Examples: (Note that the trailing slash is necessary.) >dp c:\flash\| >dp $X| - CHECKING DISK SPACE Command: >df [... optional] (disk free) Action: Displays the amount of free space on the default drive, or, if a filepath is given, on that drive. Note that the first two parameter examples listed below accomplish the same thing. Flash will not show the free space in a folder per se, since folders can hold as much as the entire drive they are on, minus a little overhead. Parameters: d: d:\filepath\ $X (any variable containing a drive specifier) Examples: >df c:| >df $X| - LISTING FILES IN DIRECTORY Command: >dd [... optional] [... optional] (disk directory) Action: Lists the folders and files in the filepath specified as the first parameter, or in the default path if no specification is given. The list is written to the screen as the default, but it can also be written to a disk file or sent out the modem port. Parameters: Note: The trailing slash is required. d:\filepath\filename.ext (any filepath; wildcards are allowed for the filename) d:\filepath\*.* AUX: (sends the list to the modem, the "AUX:" device on the ST; a space is needed in front of "AUX:") d:\filepath\*.* filename.ext (writes the list to a disk file) Examples: >dd| >dd AUX:| >dd c:\flash\*.txt| >dd a:\dofiles\*.* >dd c:\bbstexts\local\numbers.* AUX:| >dd c:\flash\do\*.do dolist.txt| - OPENING A FILE Command: op [...] (open) Action: Opens a disk file, using a standard filespec, or the Flash capture buffer, using "BUF:", to check or read the data, or opens the modem port, using "AUX:". Flash can be instructed to report on whether the operation was successful. In other words, Flash can test to see if a particular file exists -- or even any file at all exists, with wildcards -- using the "op" command. The "op" command is tested by issuing an "if" command followed by a tilde (the "~" character) in front of "op". See the context examples below for the use of "op" with files. The function of "op" with "BUF:" and "AUX:" is covered in "Making better use of the capture buffer" below. Parameters: d:\filepath\filename d:\filepath\*.* BUF: AUX: $X (any variable containing a filespec, "BUF:" or "AUX:") Examples: >op c:\wordproc\feblettr.txt| >op a:\dofiles\*.do| >op BLK:| >op BUF:| >op $X| Context examples: >op c:\flash\messages\bbsdaily.txt| >if ~op sa ca c:\flash\messages\daily.txt| >** Checks to see if the daily message file exists. If it does not exist, Flash saves the contents of the capture buffer to a new file of that name. | >op a:\errorlog.txt| >if ~op jmp noerrors| >vi a:\errorlog.txt| >L: noerrors| >** Checks for the presence of an error log and displays it on the screen if found. | - KILLING A FILE Command: >ki [...] (kill) Action: Kills (deletes) a file. The parameter can include a filepath as well as a filename, and can include wildcards. If wildcards are used, Flash deletes the first file it finds that matches the wildcard specification. Multiple deletions can be made by issuing the "ki" command with a wildcard parameter, checking to see if any files still exist in the path using the "op" command, and looping back through those two commands until the "op" command does not find a file. See the context example below. Parameters: d:\filepath\filename.ext (kills a single file in that folder) d:\filename (kills a single file in the root directory of d:) d:filename (kills a single file in the default directory; the "d:" can be omitted) d:\filepath\*.txt (kills the first file it finds in that directory having a ".txt" extender) $X (any variable containing a filespec) Examples: >ki a:\oldmsg.txt| >ki c:\flash\*.bak| >ki $X| Context examples: ** Killing all files in a pathway using wildcards ** >L: filekiller| >ki c:\flash\oldfiles\*.*| >op c:\flash\oldfiles\*.*| >if op jmp filekiller| >** If Flash cannot open any file matching the wildcard spec, the loop is broken. Otherwise, it continues to delete files. | ** Killing selected files using wildcards ** >L: filekiller| >ki c:\flash\oldfiles\*.txt| >op c:\flash\oldfiles\*.txt| >if op jmp filekiller| >** If Flash cannot open any file matching the wildcard spec, the loop is broken. Otherwise, it continues to delete files. | Using the capture buffer from a DO script ----------------------------------------- Flash's capture buffer is more than just a place to store text. It can be used to manipulate text, and it can even be used to make copies of program files and data files, in addition to text files. - TURNING THE CAPTURE BUFFER ON AND OFF Command: >ca [...] (capture) Action: Turns the capture buffer on or off. Note: Turning the capture buffer off does not affect anything already in the buffer; it merely shuts the buffer so that nothing is added. Parameters: on of (off) \ (a toggle between on and off; this is not a satisfactory way of handling the capture buffer in a script, since you may not be able to control which setting is being switched) Examples: >ca on| >ca of| >ca \| - CLEARING THE BUFFER Command: >cl (clear) Action: Clears the capture buffer. Everything is removed, whether the buffer is on or off at the time. Parameters: none Example: >ca cl| - LOADING THE BUFFER Command: >lo ca [...] (load capture) Action: Loads a file into the capture buffer from the filespec given as the parameter. This command is also listed above, under "lo". Parameters: d:\filepath\filename.ext $X (any variable containing a filespec) Examples: >lo ca a:\bixmsgs.txt| >lo ca $X| - SAVING THE BUFFER Command: >sa ca [...] (save capture) Action: Saves a file from the text in the capture buffer to a disk file using the filespec given as the parameter. This command is also listed above, under "sa". Parameters: d:\filepath\filename.ext $X (any variable containing a filespec) Examples: >sa ca a:\bixmsgs.txt| >sa ca $X| - MARKING A BLOCK WITHIN THE BUFFER Command: >mk [...] (mark) Action: The "mk" command is awkwardly specified. Depending on the parameter chosen, it marks the top or the bottom of a block in the capture buffer or clears the mark(s). The block can then be saved or placed at the end of (appended to) a disk file. Parameters: top (the beginning of a block of text) bot (the end of a block of text) cl (clear any marks) Examples: >mk top| >mk bot| >mk cl| - APPENDING A MARKED BLOCK TO THE END OF A FILE Command: >ap bl [...] (append block) Appends the marked block to a disk file (places it at the end of the file). Parameters: d:\filepath\filename.ext $X (any variable containing a filespec) Examples: >ap bl c:\flash\filelist.txt| >ap bl $X| Executing programs within Flash ------------------------------- Unlike no-frills telecommunications programs, Flash is able to run other programs within Flash. They can be GEM programs, which use the mouse and have GEM menus, or they can be either of the two types of TOS programs -- regular TOS ("The Operating System") or TTP ("TOS - Takes Parameters"). - RUNNING A GEM PROGRAM Command: >gem [...] (run a GEM program) Action: Executes a GEM program. The new program takes over and Flash disappears. When the program ends, Flash reappears. You can safely run all types of GEM programs *except* other telecommunications programs, since Flash still has control of the modem port even when it is running another program. However, you can run programs that support telecomm functions, such as an external Zmodem module. If Flash's capture buffer was turned on when the GEM program is launched, you may find that Flash will still try to store incoming data from another computer while the GEM program is running. However, this can lead to system crashes and other unexpected behavior unless the GEM program was designed to allow Flash to do this. Parameters: d:\filepath\filename.ext $X (any variable containing a filespec) Examples: >gem c:\bin\wordperf\wp.prg| >gem $X| - RUNNING A TOS OR TTP PROGRAM Command: >exec [...] [... optional] (execute) Action: Executes a TOS or TTP program. The new program takes over and Flash disappears. When the program ends, Flash reappears. You can safely run all types of TOS and TTP programs *except* other telecommunications programs, since Flash still has control of the modem port even when it is running another program. However, you can run programs that support telecomm functions, such as an external Zmodem module. If Flash's capture buffer was turned on when the TOS or TTP program is launched, you may find that Flash will still try to store incoming data from another computer while the TOS or TTP program is running. However, this can lead to system crashes and other unexpected behavior unless the TOS or TTP program was designed to allow Flash to do this. Parameters: In addition to the usual filespec parameter, TOS programs can also accept command-line switches; TTP programs *must* have command-line parameters and switches. (Their name, "TOS - Takes Parameters," indicates the need for such command-line parameters.) The most common parameters and switches may be found in archivers such as ARC.TTP and LHARC.TTP, which need to have the name of the file to be archived or extracted, along with any other instructions. Usually, the only valid command-line parameter for TOS programs is a filename. d:\filepath\filename.ext [command-line parameters and switches] $X (any variable containing a filespec and optional switches) Examples: >exec c:\STWriter\STWriter.tos mytext.stw| >exec c:\archives\lharc.ttp -x thisfile.lzh| >exec $X| - A SPECIAL CASE: THE ARC COMMAND Flash has an "exec" command that operates only on a file named ARC.TTP. It's the "arc" command. It is an alias for the "exec arc" command string. Although the official Flash documentation makes no reference to this, you could name *any* .TTP program "ARC" and run it this way (although why you would want to would not be obvious). Other commands -------------- - PUTTING FLASH ON HOLD Command: >pa [...] (pause) Action: Halts all activity for the number of seconds specified in the parameter. Parameter: # (number of seconds) Examples: >pa 3600| >pa 1| - SENDING A FORM FEED TO THE PRINTER Command: >ff (form feed) Action: Sends the printer a form feed (ejects or rolls up the current page). If the printer is not turned on, Flash will wait and then continue the script execution. Parameters: none Example: >ff| - ENDING A ROUTINE OR THE ENTIRE SCRIPT Command: >end (end the script) Action: Stops the DO script. If the script was run from another script, Flash returns to the calling script at the next command in that script. You may have more than one "end" command in a script if you are using subroutines that need to be dead-ended. However, you may find it easier to debug a long script that has such subroutines if you use a "jmp" command at those points to bring all subroutines to a common exit point. Parameters: none Examples: >end| >L: label_1| >ifi $A "failure" jmp main_exit| >ifi $A "no call" jmp main_exit| ... >L: main_exit| >end| - QUITTING FLASH Command: >xd (exit to the desktop) Action: Stops the DO script and forces Flash to quit. All variables that had been set will be lost when Flash ends unless you save them. Use SAVEVARS.DO, included with this documentation, to save variables before the "xd" command is executed. Parameters: none Examples: >xd| >L: quit_to_desktop| >do savevars.do| >xd| - MAKING FLASH DO SOMETHING ON STARTUP Command: >au (auto startup command) Action: Places a command in Flash's memory that will be executed before any other commands when Flash loads -- but only if you save Flash's configuration file before quitting that session of Flash. (See example below.) You can have multiple commands, if they are properly separated. Parameters: [any command] [any filespec] (The parameters that follow the "au" command cannot be longer than 19 characters long, including spaces.) Examples: >au do makevars.do| (runs MAKEVARS.DO on startup, to restore variables) >au vi c:\help.txt| (shows a help file as soon as Flash runs) >au ty Hello!| (types "Hello!" on the screen when Flash runs) >au b2|>menu| (rings a bell, then shows the Flash GEM menu when Flash runs) - GETTING HELP Command: >he (help) Action: Drops Flash's Help window down on the screen and halts script execution while the Help window is shown. The Help window will stay there forever if you do not remove it manually, so do not use this command in a script that runs unattended. Pressing the [undo] key removes the Help window. Example: >he| - ACTIVATING THE PRINTER Command: >pr [...] (printer) Action: Echoes text that is being captured from the modem port to the printer port. If the printer is not on, Flash will continue execution anyway. Consider a printer buffer (a software buffer such as the Codehead SPOOLER.PRG or a hardware buffer) if you plan to use the "pr" command often, since Flash can take input from the modem port much faster than most printers can print. A slow printer can force Flash to pause unduly. Parameters: on off / (a toggle between on and off; not useful in scripts because the prior state of the "pr" command may not be predictable) Examples: >pr on| >pr off| >pr /| - FREEING MEMORY FOR OTHER PROGRAMS Command: >fr [...] (free) Action: Frees a portion of the computer's memory for use by another program. This is especially handy if you have a desk accessory that refuses to run because it found insufficient memory. Memory that has been freed cannot be "unfreed" back to Flash. Please note that if you free up too much memory, Flash's capture buffer will shrink to an unusable size. Parameters: # (any number, representing the number of kilobytes of memory freed from Flash) Examples: >fr 200| >fr 0060| >fr 1024| - SETTING UP THE TYPE-AHEAD BUFFER Command: >ta (type ahead) Action: Changes Flash's command line into a one-line type-ahead buffer. Note: Previous type-ahead lines can be brought back from Flash's memory by using the up-arrow key. Parameters none Example: >ta| - OPENING THE STATUS DISPLAY WINDOW Command: >ss (status) Action: Opens the full-screen window of Flash's status display. While most of the configuration shown in the status window is duplicated in GEM menus, there are some that are shown only in the status window. The "au" (auto) command status is one of them. The only way to see if the copy of Flash that is running has an auto instruction is to open the status window. Parameters: none Example: >ss| P A R T 5 : A D V A N C E D F L A S H C O M M A N D S ------------------------------------------------------------ - ALERTING THE USER AND ASKING FOR A PRE-PROGRAMMED RESPONSE Command: >al [...] (alert box) Action: Places a GEM alert box on the screen and pauses for mouse or keyboard response to one, two or three brief choices. The alert box can have one, two or three boxed choices called radio buttons (mutually exclusive choices, like the station buttons on a car radio), and those buttons can contain numbers or text. The area above the buttons can have one, two or three lines of text. The alert command can be written to provide a keyboard shortcut for a default choice; the default button, if any, is surrounded by a thick box, and can be chosen pressing [return]. However, the mouse can always be used to click on one of the buttons whether or not a default is given. Parameters: "[#][text1|text2|text3][button text1|text2|text3]" $X # The parameters must have quotation marks and brackets as shown. They are divided into sections. The first is the icon type, if any, that is displayed within the alert box. Icon 0 is no icon, 1 is an exclamation mark, 2 is a question mark and 3 is a stop sign. Any single digit less than 1 or greater than three equals no icon. The second section, also in brackets, can be divided into three parts. It is the text of the alert box, with the "|" symbol marking the end of line 1 and line 2. (Line 3 does not need the "|" symbol.) You may have, at most, 30 characters (including spaces) in two of the parts; the third can't have more than about 25 or so depending on what else is in the alert box. (The alert command must be contained on one line. Flash can't handle a command line more than 96 characters wide, including the command itself, the space after the command, the "|" at the end and the parameters in between.) Play around with sample alert boxes to see how much you can place in the box safely before you write any alerts for normal scripts. The third section, placed within brackets also, contains the button texts. You must have at least one button, although the "text" can be blank or can be a graphic character from the ST/TT keyboard, such as a [control-B] character. The maximum length of a button text is 10 characters. The variable ($X in the generic example above) can be any letter, uppercase or lowercase, and is optional. If a variable is present, the text in the button that the user selects will be placed in the variable. Note that if you do NOT use a variable, the action of the last section is unpredictable. The last section, which is optional, should be "1", "2" or "3". It controls which button becomes the default -- the one that automatically will be selected if the user presses [return]. If you use "0" or a number greater than 3, Flash does not act in a predictable manner; Flash will either provide no default button or will make one of the buttons the default based on which button was used as a default the last time an alert box was shown. Examples: >al "[1][File exists.|Overwrite it anyway?][Yes|No]" $A 2| >al "[2][Choose a drive|to save the file to.][A:|B:|C:]" $X 1| >al "[3][WARNING!|Modem is not responding!][OK|QUIT]" $M 2| - GETTING ANY TEXT STRING FROM THE USER Command: >qu [...] (query) Action: Shows an alert box that prompts the user for up to 40 characters of input from the keyboard. The box can contain a short text of up to three lines that gives instructions for the user. This text is the first parameter of the command. The input is placed in a variable, the second parameter. The user input can include ST/TT graphics characters in addition to letters and numbers. Parameters: The two parameters are the text of the query and the variable to place the input in. Although the query box is large enough to contain a lot of text, Flash's limit on the length of command lines will keep you from writing more than about 90 characters. Each line of text can be up to 40 characters long and must end with a "|" symbol, and the entire text must be in quotes. Examples: >qu "Please type your full name:" $N| >qu "What BBS telephone number|do you want to call?" $X| >qu "Please type the password|for access to this script:" $P| - COMBINING USER INPUT WITH STRING MANIPULATION Context examples: 1. A simple request for a number to dial. The variable "X" is checked to make sure it is not blank, and the contents of the variable are then passed to the dialing command. This routine makes no attempt to check to see if the contents of the variable are indeed numbers; this can be done in Flash, but only with a great deal of effort. (A partial example of how to do that is shown below.) >L: getnumber| >qu "What BBS telephone number|do you want to call?" $X| >if ~X jmp getnumber| >ty You typed: $X.| >ty| >ty Dialing $X...| >ty| >di #$X| 2. A way to check for numbers in a variable. Flash does not have any method of treating variables as numerics instead of simple text strings, so you need to check for the presence of at least ONE number with a routine like this: >L: getnumber| >qu "What BBS telephone number|do you want to call?" $X| >if ~X jmp getnumber| >ifi $X "0" jmp ok| >ifi $X "1" jmp ok| >ifi $X "2" jmp ok| >ifi $X "3" jmp ok| >ifi $X "4" jmp ok| >ifi $X "5" jmp ok| >ifi $X "6" jmp ok| >ifi $X "7" jmp ok| >ifi $X "8" jmp ok| >ifi $X "9" jmp ok| >ty You did not type a number!| >ty| >jmp getnumber| >L: ok| >ty You typed: $X.| >ty| >ty Dialing $X...| >ty| >di #$X| 3. A way to make sure two variables are exactly the same. In one of the examples above, the user is asked for a password. The standard method of checking one variable against another is the "ifi" command ("ifin" -- meaning "if the contents of this variable are contained in the other one"). But "ifi" checks only for a non-exclusive match; Flash just checks to see if the string in one variable is *included* in the other one. In other words, a variable containing the string "John" will pass an "ifi" comparison against a variable containing the string "Johnson" and a variable containing the string "Johnny on the Spot." If you want to make an exact match, you have to resort to some string manipulation. That's not puppet talk; it's the way you can turn a text string entered by the user into something else. The easiest way is to add front and back delimiters to the string. They mark the beginning and the end, so you can compare another string for an exact match for content and length. Here's how that's done. In the example below, variable X takes over from variable P for password checks. The actual password is stored in a file called PASSWORD.DAT, which consists of all the passwords, one to a line. The "inp" command reads each line of the PASSWORD.DAT file into a variable, and that variable is checked against the user input. (Note that the user gets only a few chances to type the password right. This is done by a loop that increments a counter. When the counter reaches as certain value, the routine bounces the user out of the script.) >L: start| >$C 0| >jmp getpw| >L: RetryLoop| >ifi $C "0" jmp increment0| >ifi $C "1" jmp increment1| >ifi $C "2" jmp increment2| >ifi $C "3" ty Too many failures! Script aborted.| >ifi $C "3" end| >L: getpw| >qu "Please type the password|for access to this script:" $P| >if ~P jmp getpw| >$X &$P& >** The user string now begins and ends with the "&".| >op password.dat| >if ~op ty Password data corrupted! Please run SETUP.DO!| >if ~op end| >L: InputLoop| >inp $A| >if eof jmp NotFound| >** If the end-of-file mark is reached before a match is made,| >** the password is not there.| >$B &$A&| >ifi $B $X jmp pwOK| >jmp InputLoop| >** password not found routine| >L: NotFound| >ty Password not found. Please notify the system programmer.| >ty| >end| >** counter increment routine| >L: increment0| >$C 1| >jmp getpw| >L: increment1| >$C 2| >jmp getpw| >L: increment2| >$C 3| >jmp getpw| >** password ok routine| >L: pwOK| >ty Password accepted. Launching script...| >ty| >do anyscript.do| >end| Handling text input and text strings ------------------------------------ - GETTING REMOTE INPUT Command: >ge [...] (get) Action: Gets a text string from the other computer across the modem port. The maximum length of the string is a little over 100 characters. It's important to note that the "ge" command recognizes a carriage return as the end of the string, but does not include it in the string that it saves in Flash's input buffer. This means that a bare carriage return sent from the other computer will be interpreted as an empty string. Flash *can* find empty strings, however, as we shall see below. Parameters: $X (any variable) Example: >ge $B| Context example: >se "Please type your name.|"| >ge $N| - CHECKING FOR THE SPECIFIC CONTENTS OF A VARIABLE Command: >ifi [...] [...] [...] (ifin) Action: Looks at a text string contained in a variable to see if there is a matching string. If it finds one, Flash executes the command given after the string comparison. The string does not need to be a complete match for the full text of the variable's string; all Flash does is check for its inclusion (thus the name "ifin" in the full spelling of this command, which means "if in string X you find string Y, you've got a match"). This means that the string "Harry" is contained in the string "Harry's Bar and Grill," as is the string "ar" (in fact, it is in there twice). But the string "Harry's Bar and Grill" is *not* contained in the string "Harry". Be careful to place your comparisons properly so that the strings are compared the way you want them to be. The "ifi" command always works in this order: If in string 1 is string 2, execute a command. Flash does not check for the case of the string characters in the comparison. "The" is the same as "the" and "tHe" and so on. Parameters: First parameter: $X (any variable) Second parameter: $X (any variable) or any text string Third parameter: any Flash command Examples: >ifi $X "Yes" jmp showmenu| >ifi $Y "Monday" al "[1][Do weekly backups?][Yes|No]" $Z 1| Context example: >L: top| >qu "Type the name of the script:" $X| >ifi $X ".do" jmp nameOK| >al "[3][""DO"" extender missing!Try again?][Yes|No]" $Y 1| >ifi $Y "Yes" jmp top| >do $X| - TESTING FOR EMPTY VARIABLES AND SUCCESSFUL COMMANDS Command: >if [~] [...] [...] Action: The "if" command is quite powerful. In essence, it tests a condition. One use is to test a variable. Tests for *any* string in a variable, or for a null in a variable. The first parameter (or, more properly, a command switch) is the "~" symbol, which inverts the command, so that it checks for a null. A null is an empty variable, also called an empty string. You can create a nulled variable yourself, or a variable can become nulled if Flash is waiting for user input and receives only a carriage return. Unlike all other Flash commands that use variables, the "if" command is *not* followed by the "$X" designation of a variable, but only by the character representing the variable, without the dollar sign. Thus you have "if X" and *not* "if $X". Parameters: Optional switch: ~ (turns "if" to "if not") First parameter: X (any variable, without the "$") Second parameter: any Flash command Examples: >if X se "Thanks for the response!|"| >if ~D ty Date not set.| Context example: >L: top| >se "Please type your name.|"| >ge $N| >if ~N se "You must type your name.|"| >if ~N jmp top| >se "You typed: $N.|"| >se "Is this correct? (Y/n): |"| >ge $C| >if ~C se "Sorry, we must log you off...|"| >if ~C hg| >ifi $C "Y" jmp nameOK| >jmp top| The other uses of the "if" command test for the successful completion of a command or a condition. The commands all use "if" the same way, with the "~" used to invert the meaning. Not all commands or conditions can be tested; here are the ones that are included: ca (carrier; checks for presence of modem carrier) >if ca [command] >if ~ca [command] di (dial; checks for completion of dial command) >if di [command] >if ~di [command] eof (end of file; used when inputting data) >if eof [command] >if ~eof [command] op (open; checks for presence of a file) >if op [command] >if ~op [command] ul (upload; used to tell if an upload was OK) >if ul [command] >if ~ul [command] wa (wait for a string; checks if the string was found) >if wa [command] >if ~wa [command] Simple examples of The "if" command ----------------------------------- Usually, the "if" command is thought of as essential for remote DO scripts -- those that run while you are asleep, for example, as you might want to do when calling a long-distance BBS or a busy telecomm service. But it can also be very useful in scripts that are running when you are at the console. The "if" command can be made to check on a number of things that your computer can do better (or at least faster) than you can. Here is a simple dialing routine using "if" with the "di" command: >L: makecall| >di #123-4567| >if ~di al "[1][Dial failed!|Try again?][Yes|No]" $X 1| >ifi $X "Yes" jmp makecall| Here is a routine that makes sure your modem still has a carrier before it tries an upload or download: >if ca ul myfile.ext| Here is a way to make Flash repeat an upload attempt if necessary. It also checks for a carrier and checks to see if the "wa" command failed: >L: makeupload| >se "U|"|>** upload command sent to a BBS.| >wa "Ready"|>** wait for string from BBS.| >if ~wa jmp warning| >if ca ul myfile.ext| >if ~ul jmp tryagain| >end| >L: tryagain| >pa 5|>** pause for any length of time to let BBS react.| >se "U|"| >wa "Ready"| >if ~wa jmp warning| >if ca ul myfile.ext| >if ~ul jmp warning| >end| >L: warning| >al "[3][Upload attempt failed!|Try again?][Yes|No] $Y 2| >ifi $Y "Yes" jmp makeupload| >end| Checking to see if a file exists -------------------------------- The "op" (open) command has two primary uses when dealing with disk files. The first is to open a file so that the contents can be read line-by-line. We'll get to that shortly, but we should first see how "op" can be used to do nothing more than confirm that a file exists. This is done through the "if" command. Here is an example: >op myfile.ext| >if op al "[1][File exists!|Overwrite it anyway?][Yes|No] $X 2| >ifi $X "Yes" sa ca myfile.ext| The same technique can be used to see if a folder exists. Flash cannot see folders that way it can see files, but that shouldn't get in the way if you intentionally test for the presence of a folder by trying to save a file to that folder. Here's an example, which uses the "log" command to create a small text string in the capture buffer and then tries to save that string to a file: >$X|>** Var. X is nulled so it can be used below.| >ca on| >ca cl| >log "This is a string of test data.|"| >sa ca foldname\test.dat|>** any folder name can be used.| >op foldname\test.dat| >if ~op al "[1][Folder does not exist!][Sorry!]" $X 0| >ifi $X "Sorry" end| >al "[1][Folder located!][Thanks!]" $X 0| >ca cl| >end| A routine like the one above could get a lot fancier. The only thing Flash cannot do unaided is create a folder. It can easily find any folders, however, so it wouldn't hurt to make sure you have various folders already created, even if they are empty. Getting Flash to read data from a file -------------------------------------- Reading data from a file is a good way of making Flash check the contents line-by-line. The process actually goes fairly quickly if the file is read from a fast hard disk or from a ramdisk. If your computer has a lot of memory, you can make the process even faster by loading the data file into the capture buffer and reading each line from the buffer. Please note that the data file should be a *formatted* text whenever possible -- in other words, a file just like the one you are reading, with lines that do not exceed the screen width. Lines that are longer than about 90 characters are truncated by Flash (the ends are cut off), which will keep Flash from seeing whatever was located past that point on each line. Why would you want to have Flash read a data file? There are quite a few good reasons. If you regularly run a DO script (or a series of scripts) while Flash is running unattended, you may want to have Flash save an error.log to disk. Later, Flash can automatically check the error.log for various entries, alerting you if it finds some that are serious problems. A sexier use might be to have Flash automatically read a message file for certain key words. In other words, you could create a script that turns Flash into a sort of database manager, alerting you to text files that you may want to read (and saving you the trouble of paging through text files that aren't worth reading). The basic routine that you *must* (and I mean *must*!) use follows this pattern: >op filename.ext| >if ~op end| >L: looptop| >in $X| >if eof jmp loopend| >ifi $X "target string" jmp loopend| >jmp looptop| First you must open the file. Then you must have a label at the top of the input loop. The next command must be the "in" (input) command, using a variable to store the data. The very next command *absolutely must* be a check for the end-of-file marker; otherwise, your loop could go on forever. The next line uses the "ifi" (ifin) command to check for the presence of the string you are looking for in the data file. If the string is not found, Flash loops back to the top and inputs the next line and starts the search again. You can, of course, have Flash search for more than one target string. Obviously, with 26 possible variables, you can specify 26 separate target strings. It's even possible to search for more than 26, by manipulating the strings. (I'll let you work that out for yourself as a little challenge. Write to me if you manage it in a clean fashion -- no thousand-line DO files, please!) Here's the same routine as the one above, with multiple target strings: >op filename.ext| >if ~op end| >L: looptop| >in $X| >if eof jmp loopend| >ifi $X "target string 1" jmp loopend| >ifi $X "target string 2" jmp loopend| >ifi $X "target string 3" jmp loopend| >ifi $X "target string 4" jmp loopend| >ifi $X "target string 5" jmp loopend| >ifi $X "target string 6" jmp loopend| >jmp looptop| After you've set up Flash to check for target strings in a data file, what do you do with them? You'll need to create another routine, or perhaps a separate DO script, to process the information that Flash picked up from the data file. In the example below, I'll assume that you want Flash to check the current message download from a BBS for any mention of the ST, the TT or Atari. This will be a rudely basic example, and you'll probably want to make it a lot more specific. First, here's a tip on how to make sure Flash finds the character strings you are really looking for. The precise string you are looking for should be delineated in some way, probably by placing a space in front of and behind it. For example, if you want Flash to find the string "ST" in the data file, you should list that string twice in your "in" command -- once with a space in front of it, and once with a space behind it. This will keep Flash from finding the two letters "st" within such words as "fast" or "stupid" (I know, who would dare put the word "stupid" in a BBS text file? But you never know....) Once the file has been checked, you should branch to a routine that makes use of the variables. This is what we'll be doing below. (In this routine, the string "Atari" is specific enough, so we won't place spaces around it.) >$S| >$T|>** These must be nulled at the start.| >$A| >op bbsmsg.txt| >if ~op end| >L: looptop| >in $X| >if eof jmp loopend| >ifi $X " ST" jmp st_found| >ifi $X "ST " jmp st_found| >L: tt_search| >ifi $X " TT" jmp tt_found| >ifi $X "TT " jmp tt_found| >L: atari_search| >ifi $X "Atari" jmp atari_found| >jmp looptop| >L: st_found| >$S the ST| >jmp tt_search| >L: tt_found| >$T the TT| >jmp atari_search| >L: atari_found| >$A Atari in general| >L: loopend| >if S jmp combine_vars| >if T jmp combine_vars| >if A jmp combine_vars| >$B No mention of the ST, the TT or Atari in general found.| >jmp store_B| >L: combine_vars| >if ~A jmp no_A| >if ~T jmp no_T| >$B Search found mentions of $S, $T and $A.| >jmp store_B| >L: no_A| >if ~T jmp no_T| >$B Search found mentions of $S and $T.| >jmp store_B| >L: no_T| >$B Search found mentions of $S.| >L: store_B| >ca on| >ca cl| >log $B| >log| >sa ca msgalert.dat| >ca cl| >vi msgalert.dat| >** msgalert.dat is shown on the screen.| >end| You could try many varieties of the script above. One variation would be to have Flash show you each line of text that contains the target string(s). All you'd need to add to do that are these two lines right after the "xx_found" labels: >ty $X >ty| Or you could place all the lines of text that contain the target strings into Flash's buffer, and then save the buffer. To do that, use this line in place of the two lines above: >log $X| and then save the capture buffer when the loop is finished. Using a data file to check your drives -------------------------------------- By writing a script that does nothing except write a line of data to a file, you can have Flash try to open the file on each drive in your computer's system. Files that fail to open don't exist -- and that means there must be some sort of trouble with the drive. Here's an example: >ca on| >ca cl| >log This is a line of test data.| >sa ca a:\test.dat| >op a:\test.dat| >if ~op al "[1][Trouble with Drive A:!][Thanks!]" $X 0| >sa ca b:\test.dat| >op b:\test.dat (etc..) P A R T 6 : F L A S H ' S H I D D E N F E A T U R E S ------------------------------------------------------------ Flash has a file copier -- and it's not just for texts ------------------------------------------------------ Flash's text storage area is called the capture buffer. Any time you type something into the text editor, you are using the capture buffer. You can also load a text from a disk file into the capture buffer, and of course you can save text that is coming across the modem port into the buffer. The "sa" (save) command allows you to save whatever is in the capture buffer to a disk file. Since the capture buffer is used by the text editor, most users probably assume that they cannot use the capture buffer to hold program files. And few may have understood that the capture buffer can also be used to copy software. In other words, you can load a binary file (a program) -- not just a text file -- into the capture buffer and then save the buffer to another location. If you have a large enough capture buffer, you can use it to copy even very large programs. I know someone out there is going to insist that this sort of thing can't possibly work. The standard argument I've heard from Flash users who haven't tried this method is that Flash's capture buffer has a built-in word-wrap, and this word-wrap will somehow mess up the binary file. They've suggested that it might work if Flash's word-wrap is turned off. But no matter what the setting of word-wrap, Flash does not try to wrap (place carriage returns into) binary data that is loaded into the buffer. This has nothing to do with binary data; it's just that Flash does not wrap *any* data that is placed in the buffer. Word-wrap has no effect until you either start typing or press F10 (the reformat key). If you use the capture buffer merely as a storage area, no characters or data in the original file are altered in any way, and the saved version of the buffer is exactly the same as the original file. Here's an example of using Flash to copy the program ARC.TTP from one folder to another: >ca on| >ca cl| >lo ca c:\archive\arc.ttp| >sa ca d:\temp\arc.ttp| >ca cl| Of course, you can also change the name of the file when you copy it. And that means that you can use Flash to rename files of any kind merely by loading a file into the capture buffer, saving it with a new filename, and then killing the original file. Here is an example: >ca on| >ca cl| >lo ca c:\flash\funckey.def| >sa ca c:\flash\bbsfkey.def| >ca cl| >ki c:\flash\funckey.def| Flash has "gosubs" just like BASIC and C ---------------------------------------- One of the biggest complaints about Flash from users who have created their own Flash DO files is the apparent lack of a "gosub" facility. A "gosub" is a variation on the familiar "goto," which in Flash is called a "jmp." A "jmp" command forces Flash to find its next instruction not at the following command but at a label anywhere else in the DO script. It looks like this: >jmp SomeLabel| ... >L: SomeLabel| The problem with all "goto" commands, including Flash's "jmp," is that the program does not automatically return to the point where the "goto" instruction was issued. A "jmp" does not tell Flash to go to another instruction and then return to the place it had been; rather, it is a doorway, so to speak, that only opens in one direction (unless, of course, you write the script with a return "jmp" back to the original location -- something that can be chancy if you're not really careful). A "gosub" is a goto-and-return command, used to access such things as subroutines that work with the main script. Here's a simple one, an imaginary Flash "gosub" that calls up a help screen any time a user presses . You'd want a "gosub" used here because the script should not have to proceed to any other point except the "help" subroutine: >L: top| >al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0| >ifi $X "Xmodem" jmp XmodemXfer| >ifi $X "Quit" jmp Quit| >ifi $X "Help" gosub HelpScreen| >if ~X jmp top| Another such subroutine might be a date-setting procedure. When the main script is running, it can be programmed to check for a current date; if it does not find one, the main script would then use a "gosub" to branch to a date-setting subroutine, which would return to the next command in the main script after it had run. It would look something like this, if Flash had a "gosub" (variable D would hold the date): >mo ansi| >ba 2400| >if ~D gosub DateSet| >di starbbs| Here's another example, using an imaginary "gosub" to look for caller passwords in a simple Flash-based BBS: >L: top| >hg|>** hang up| ATS0=1| >** send answer command to modem (on first ring)| >wa "CONNECT"| >send " Welcome to the Flashland BBS.|"| >send "Please type your password: "| >get $P| >if ~P jmp top|>** reset modem if no response| >gosub CheckPW| >ifi $C "password OK" send "|You are now on line.|"| >ifi $C "password OK" jmp mainmenu| >send "|Password not found!|"| >gosub GetNewPW| >L: mainmenu| ... In each case above, Flash actually *does* have a gosub that can be used. In fact, there are two different ways of doing it. The first involves spawning a new script that is executed from within the current script. This uses the "do" command. Whenever another DO file is executed from within a running DO file, the new script is executed and then the command execution returns to the command following the one that issued the "do" command -- a perfect "gosub." This method works very well, especially if the scripts are all running from a fast hard drive. The primary drawback should be obvious: Flash does not allow nested DO files past three levels, so you should be careful to keep track of how many levels deep you may be going when you nest any scripts. There's another caution, too, which will be mentioned a little later. Here's another version of the first example given above, using a nested DO file instead of the non-existent "gosub": >L: top| >al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0| >ifi $X "Xmodem" jmp XmodemXfer| >ifi $X "Quit" jmp Quit| >ifi $X "Help" do help.do| >if ~X jmp top| And here is the second example above, using the "do" command as a "gosub": >mo ansi| >ba 2400| >if ~D do date.do| >di starbbs| Likewise, the third example would work fine if "do" commands were used instead of "gosubs" where necessary. The second way of getting "gosubs" in Flash is not used much, judging from the scripts that I have seen. But it is quite powerful, and does not have a nesting problem. It involves the use of function-key strings -- commands that are inserted in function keys 1 through 20 and called from a script using the "go" command. Whenever a "go" command is executed, the script continues at its next command after the function-key string is passed to the program. In actual execution, the "go" is a true "gosub." What makes this even more useful is Flash's ability to program function keys from within DO files themselves, using the "fk" command. This means that the main script can set up a function key in any way it wants, and then branch to it if needed. To use this feature properly, you must understand how Flash passes function-key strings to a function key. Because these "fkey" commands are also script commands, you must be sure that Flash does not execute them when it is merely loading them into an fkey. The way to do it is to use single quote marks around the entire fkey string; when Flash encounters a single quote mark, it ignores all commands between that mark and the next one it comes to. (Things can get complicated if you are also inserting quotes into a function key, but Flash also has a way of getting around that, as we'll see shortly.) Let's change the first example above so that the "help" subroutine is accessed through a function key. First, the fkey must be set up; that's the second line in the example below. >L: top| >fk 1 '>$X|>vi help.txt|'| >al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0| >ifi $X "Xmodem" jmp XmodemXfer| >ifi $X "Quit" jmp Quit| >ifi $X "Help" go 1| >if ~X jmp top| A sharp-eyed Flash user may be able to notice that the same effect might be achieved without using the equivalent of a "gosub" in the example above, by changing one line and adding another, while deleting the fkey loader, like this: >L: top| >al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0| >ifi $X "Xmodem" jmp XmodemXfer| >ifi $X "Quit" jmp Quit| >ifi $X "Help" vi help.txt| >ifi $X "Help" jmp top| >if ~X jmp top| But this method is not reliable once your commands become more complicated. Using the "go" command is foolproof and should not give you any trouble. What about the problem of placing quote marks in commands when you assign fkey strings from a DO file? Here's where this kind of problem can arise: You may want your fkey to have quotes built into the contents of the string, such as when you are assigning an alert box to the function key. Alert box commands *must* have quotes in them, as in the second line of the example above. Here's how to do it. Use double quotes instead of single quotes when you create the fkey string. In other words, place a double quote in front of every double quote that you want to have Flash pass through to the function key. Here's how it would look: >ty | >fk 1 '>al ""[2][Xmodem transfer?][Xmodem|Quit]"" $X 0|'| >go 1| >ifi $X "Xmodem" jmp XmodemXfer| >ifi $X "Quit" jmp Quit| By the way, the same method works in any situation in which you want to pass a quote mark through Flash without having it changed or acted on (when you are logging text to Flash's capture buffer, for example). Flash can be more than a program; it can be a shell --------------------------------------------------- A shell is merely a program that runs other programs. The ST and TT GEM desktops are shells, for example. But the most common shells that advanced ST and TT users are likely to encounter are command-line shells. An excellent shareware shell is Tomshell.prg, which is distributed with STalker. Unix-like shells are also common among some users. Some shells let you set up function keys to run programs, and others offer advanced batch-file capabilities. Flash can do all that. All you need to do is try it. To use Flash as a shell, run it from the GEM desktop and then set up function keys that run your favorite programs. You'll probably find that most of your programs run just fine -- except for other telecommunications programs. Some of them will cause a conflict with Flash over which one is controlling the modem port. A function key that is set up to run a program should look like this, if you set it up from a DO script: >** setting up F4 to run STWriter...| >fk 4 '>ex STWriter.prg|'| Note that if the program you are running is not in the same folder as Flash, you will have to do one of two things: Either place the full pathname in the fkey command string, or change the default directory to the program's directory before running it. Some older GEM programs have resource files (files with a ".RSC" extender) that won't be found unless you switch to the program's folder first. Here are the two variations on the routine above, with the second one needed to run some GEM programs: >** setting up F4 to run STWriter...| >fk 4 '>ex c:\stw\STWriter.prg|'| >** setting up F4 to run STWriter...| >fk 4 '>cd c:\stw\|>ex STWriter.prg|'| After you run that command in a script, press F4 to run STWriter within Flash. When you quit STWriter, Flash's familiar terminal screen will reappear. If you program and load function keys to run various programs, you should be sure to save those function keys so that they are available the next time you run Flash. You don't need to save them as the default function keys; you can use another filename and then load them by another function key. Here's an example on how to do it from a DO file: >** setting up fkeys and making an fkey loader.| >sa fk funckey.def|>** saves current keys.| >fk 1 '>fk|'| >fk 2 '>cd c:\wp\|>ex wp.prg|'| >fk 3 '>ex c:\icd\hdutils.prg|'| ... >fk 19 '>ex c:\qf.prg|'| >fk 20 '>lo shellkey.def|'| >sa fk shellkey.def| Function key 1, in this example, is the Help key. When you press it, all it does is show you a list of function keys and their assignments -- a handy way of seeing all 20 at once. Fkey 20 is the loader. Flash always boots up with the function keys that are in the file funckey.def, but you can switch easily to a new set of fkeys by using the F20 method above. (In my own setup, I've gone a step further. F20 loads a set of function keys that are themselves separate fkey loaders. This way I am able to have as many separate function keys as I want, since F20 in the first loader file could also load *another* set of fkey loaders, and so on for the second and third set.) You may also want to note that function keys can also include comments, like this (in a script routine that sets up an fkey): >fk 5 '>** shows general help file|>vi genhelp.txt|'| And you might find it handy to create function keys that do nothing by themselves -- in other words, fkeys that do not operate unless you press after you press the fkey. The one I've used the most is an fkey that clears Flash's capture buffer if I press . if I press , it cancels out. It uses the comment command to show a comment in Flash's command-line window (the one at the bottom of the terminal screen). Here is how to load it from a script: >fk 10 '>ca cl ** clears buffer; cancels'| You'll note that function key 10 is not written "properly" -- that is, it does not end the way fkeys are supposed to end, with a "|" character. As a result, when you press F10, the commands in the function key are not executed. But if you press , the missing "|" is supplied and the commands are executed. Pressing clears the command line and cancels the fkey. Flash can do Zmodem easily -------------------------- The "fact" that Flash can't do Zmodem is one of the biggest fictions among the Flash lore. Because Flash does not have a "Zmodem" entry in the GEM Upload and Download menus, some users assume that there is no way to do Zmodem transfers within Flash. But all Flash needs is a Zmodem module. The best is Alan Hamilton's shareware program XYZ, which comes in both GEM and non-GEM versions (xyz.prg and xyz.ttp). Both are available from GEnie and other telecomm sources. When you are ready to do a Zmodem transfer, simply issue a "gem xyz" or "ex xyz" command. (You must use the "gem" command if you want to run a GEM program and be able to use your mouse.) I've found xyz.ttp much easier to use, since you can pass commands and filenames to the program from a function key. After you press the fkey, type the rest of the information on the Flash command line and press . Here's a sample fkey as it would be set up from a script: >** fkey 11 to receive Zmodem, fkey 12 to send.| >fk 11 '>ex xyz -r|'| >fk 12 '>ex xyz -s '| Note that the command in fkey 12 does not end. When fkey 12 runs, it waits for your input, which in this case would be the filename or wildcards for whatever you want to upload. Flash is a graphics program --------------------------- Can you see graphics without running another program within Flash? You sure can. You can easily show a full-screen graphics picture based on any Degas high-resolution or medium-resolution picture. You do it by converting the Degas graphic to Vidtex, and then using the "vi" (view) command in Flash. Flash's "vi" command shows a text file on the screen, but if Flash is placed in its Vidtex emulation mode (also "vi"), you'll see any Vidtex pictures with the view command as well. Included with this documentation is a copyrighted program, VCONVERT.PRG, which converts pictures from Degas to Vidtex. The program is freeware. Also with this documentation are a number of Vidtex pictures that you can view with Flash/ To see Vidtex pictures, you should have the emulation mode set to Vidtex. Here is a sample DO command line: >mo vi| To view them, use the other "vi" command. You can set up a function key that needs your input to show the picture. Here's an example: >fk 7 '>vi |>** Type filename of Vidtex picture'| Flash can automate your file backups ------------------------------------ Backup programs are great, and they're an absolute necessity if you don't want to lose what's on your hard drive. But between backups, you can use Flash to automatically save your files in archives (compressed files that may contain many standard files). The actual archiving, of course, is done by a program such as LHARC or ARC; what Flash does is execute the archiver at specified times and under specific conditions. Flash's DO language and its variables make this quite easy. Here's how it's done. First, this method of archiving takes advantage of one of the lesser known commands in both LHARC and ARC, the "update" command. Normally, the main functions of LHARC or ARC are the creation and extraction of archives. The commands to do this are "a" (archive) and "e" (extract). But if you use LHARC or ARC for backing up files, the command that may be most useful is "u" (update). The update command forces LHARC and ARC to look at the time-and-date stamp that is always placed on a file. Each time the file is changed in any way, the ST/TT operating system updates that time/date stamp. By checking all the files in an archive for the time/date stamp, the "update" command knows which files in the archive need to be updated. In a neat additional feature, "update" also *adds* any files to the archive that are not there already. This gives you a simple way of maintaining a separate, continually updated copy of your essential files, without needing to do anything more than running a DO script. If you are in the habit of running a master script every day, as I do, you need do no more than add a line to the master script to execute the backup DO file. I use just such a method to keep a backup archive of the auto folder on my C: drive, and I also use it to keep a backup archive of all my DO files. (Because I enjoy programming DO scripts, I usually write new ones or change current ones every few days.) Using LHARC or ARC to update archives does place one extra requirement on your computer: You should have a built-in clock, or, if that is not feasible, you must make sure you enter the current time and date each time you boot your ST. (All STe models, Megas and TTs have clocks built in.) You can change your computer's clock from the Atari CONTROL.ACC, from the company's CPX-based XCONTROL.ACC, or from many other desk accessories and programs. Since you already have a modem, my advice for those who do not have a built-in hardware clock -- and those who want to make sure the clock that they do have in their computer is accurate -- is to use CALLTIME, a program written by Bob Areddy, and available (at the time this is being written) as CALLTIM3. You may be able to find it on a local BBS, and should be able to download it from GEnie. (It may be called CALLTIM3.ARC or CALLTIM3.LZH.) CALLTIME uses your modem to dial the U.S. Navy Observatory near Washington, D.C. and pick up the precise time from the observatory's atomic clock. It automatically sets your computer's internal clock and hangs up. A call should not cost more than 15 to 30 cents at night. (My calls average about 14 cents, at a distance of about 400 miles from Washington.) If your computer has a built-in hardware clock, CALLTIME will reset it, and it will remain accurate even when you have rebooted after the computer has been turned off. (Hardware clocks are always running, even if the computer is off.) If you do not have a hardware clock, your ST still has a software clock, and it will be set accurately and should remain accurate to within a few seconds a month as long as your ST remains on. Here are the essential parts of two scripts for automatic file backup. The first backs up all new and altered files in the C:\auto\ folder, and the second backs up DO files. >** This script must have a folder in the C: root| >** named AUTOFBAK. It creates and maintains an archive| >** called AUTOFLDR.LZH in that folder.| >cd c:\auto\| >$X d:\arc\|>** path of the archive program; use yours.| >ex $Xlharc u c:\autofbak\autofldr *.*| >pa 1| >ty | >ty Auto folder backed up successfully!| >ty|>ty| >** This script must have a folder in the Flash directory| >** named DO, and a folder inside that folder| >** named BACKUPDO. Change the "cd c:\flash" command to| >** your drive and folder path for Flash.| >cd c:\flash\| >$X D:\arc\|>** see comment above.| >$Y "do\backupdo\"| >ex $Xlharc u $Xdofiles.lzh do\*.DO| >ty | >ty Do scripts backed up successfully!| >ty|>ty| ** A note about incompatible LHARC versions ** In the two examples above, the version of LHARC that is used is the latest version of the so-called "Quester" LHARC, named for Thomas Quester of Germany. Quester has done a lot to improve LHARC, which was written by a Japanese programmer for IBM compatible PCs. Quester's LHARC is almost fully compatible with its current PC counterpart, now called LHA, but it is *not* fully compatible with earlier versions of LHARC for the ST and TT. If, as I do, you use the excellent desk accessory UNLZH to extract, test or read the contents of LZH files, you should consider using an additional command when you run LHARC from a DO file. That command is actually a "switch" (an added instruction that modifies a command), given as "-o" after the main command. The "-o" switch forces LHARC to revert to an older compression method that UNLZH accepts. Here is how the command looks in a DO file line: >ex $Xlharc u -o $Xdofiles.lzh do\*.DO| Flash can maintain files by day and date ---------------------------------------- If your computer has a built-in hardware clock, or if you make sure you set your ST's time and date each time you boot up (see the note about CALLTIME above if you want it done by modem), you can use the script DATE.DO to set some of Flash's variables to the current day and date. DATE.DO, which is distributed in the archive with this documentation, gets its information about the day and date from a freeware program named TIMEDATE (or TD in some versions), also distributed in the archive. TIMEDATE creates a data file, stored on disk, that DATE.DO reads to interpret the data needed for Flash's variables. In DATE.DO, variable A is the full date in the U.S. format (August 3, 1993). Variable B is the full date in Canadian format (3 August, 1993). Variable D is the day in one or two digits (3 or 22); variable M is the month, spelled out (August); variable O is the month in two digits (08); variable W is the year in two digits; variable X is the year in four digits (1992), and variable Y is the time that DATE.DO was run, using a European version of the standard 24-hour format (14:42.15). Flash can find its DO scripts and run them ------------------------------------------ Some of you may be familiar with Procomm Plus, the most popular telecommunications program for IBM-compatible PCs. One nicety about PC Plus is the way it automatically executes its scripts even if you don't type the filename extender. In other words, even though PC Plus ASPECT scripts, the equivalent of Flash's DO files, are supposed to named FILENAME.ASP, you can run them by giving the FILENAME part of the name without the .ASP at the end. Too bad Flash can't do that -- or can it? Yes, it can, with a little help from you. First, we are assuming that you will, in fact, want to give all your scripts the .DO extender. This makes them easy to find and easy to sort, and it also makes sure there is no doubt about what they, um, "do" ... if you'll pardon the pun. So the next step is to write a short script called "DO" -- yes, that's the entire name, with no extender. It will be the *only* script without an extender. We can get away with this, for one DO file only, because this one will be the script that lets you run the others without bothering with typing the ".DO" extender. Here's the essential part of the script: >** filename: DO Tip: run this from a function key. This script assumes that the DO files are located in the current directory or in a folder named DO one level down in the current directory. | >L: top| >$Z .| >op *.do| >if op jmp getdoname| >op do\*.do| >if op jmp setc.d| >** Do NOT take out the double quotes in the next line!| >qu "Folder for DO files|(don''t type ""\""):" $Z| >op $Z\*.do| >if op jmp getdoname| >if ~op al "[3][Folder not found!][Rats!|Quit]" $X 2| >end| >L: getdoname| >cd $Z| >qu "Execute which DO script?|(Type ""?"" for a list.)" $X| >ifi $X "?" jmp listdo| >op $X| >if ~op jmp adddo| >if op jmp doit| >L: nofile| >al "[3][File not found!|Try again?][Yes|No]" $X 1| >ifi $X "Yes" jmp getdoname| >end| >L: adddo| >$Y $X.do| >$X $Y| >op $X| >if ~op jmp nofile| >L: doit| >do $X| >end| >L: listdo| >dd *.do filelist.txt| >vi filelist.txt| >jmp getdoname| >L: setc.d| >$Z do\| >jmp getdoname| >** end| <--== E N D ==-->